---
type: integration
title: '@astrojs/node'
description: "Apprenez à utiliser l'adaptateur @astrojs/node pour déployer votre projet Astro."
sidebar:
  label: Node
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/node/'
category: adapter
i18nReady: true
---

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import Since from '~/components/Since.astro';
import { Tabs, TabItem } from '@astrojs/starlight/components';

Cet adaptateur permet à Astro de déployer vos [routes et fonctionnalités rendues à la demande](/fr/guides/on-demand-rendering/) vers des cibles Node, y compris [les îlots de serveurs](/fr/guides/server-islands/), les [actions](/fr/guides/actions/) et les [sessions](/fr/guides/sessions/).

Si vous utilisez Astro comme générateur de site statique, vous n'avez pas besoin d'adaptateur.

## Pourquoi Astro Node.js

[Node.js](https://nodejs.org/fr/) est un environnement d'exécution JavaScript pour le code côté serveur. `@astrojs/node` peut être utilisé soit en mode standalone, soit comme middleware pour d'autres serveurs http, tels que [Express](https://expressjs.com/).

## Installation

Astro inclut une commande `astro add` pour automatiser l'installation des intégrations officielles. Si vous préférez, vous pouvez [installer les intégrations manuellement](#installation-manuelle) à la place.

Ajoutez l'adaptateur Node pour activer le rendu à la demande dans votre projet Astro avec la commande `astro add`.
Cela installera `@astrojs/node` et apportera les changements appropriés à votre fichier `astro.config.*` en une seule étape.

<PackageManagerTabs>
  <Fragment slot="npm">
    ```sh
    npx astro add node
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```sh
    pnpm astro add node
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```sh
    yarn astro add node
    ```
  </Fragment>
</PackageManagerTabs>

Désormais, vous pouvez activer [le rendu à la demande par page](/fr/guides/on-demand-rendering/#activation-du-rendu-à-la-demande) ou définir la configuration de sortie de votre compilation sur `output: 'server'` pour [restituer toutes vos pages par défaut sur le serveur](/fr/guides/on-demand-rendering/#mode-server).

### Installation manuelle

Tout d'abord, ajoutez l'adaptateur Node aux dépendances de votre projet en utilisant votre gestionnaire de paquets préféré.

<PackageManagerTabs>
  <Fragment slot="npm">
    ```sh
    npm install @astrojs/node
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```sh
    pnpm add @astrojs/node
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```sh
    yarn add @astrojs/node
    ```
  </Fragment>
</PackageManagerTabs>

Ensuite, ajoutez l'adaptateur à votre fichier `astro.config.*` :

```js title="astro.config.mjs" ins={2,5-7}
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  adapter: node({
    mode: 'standalone',
  }),
});
```

## Configuration

`@astrojs/node` peut être configuré en passant des options dans la fonction de l'adaptateur. Les options suivantes sont disponibles :

### `mode`
<p>
**Type :** `'middleware' | 'standalone'` <br />
</p>

Contrôle si l'adaptateur se construit en mode `middleware` ou `standalone`.

* Le mode `middleware` permet à la sortie de compilation d'être utilisée comme middleware pour un autre serveur Node.js, comme Express.js ou Fastify.
* Le mode `standalone` crée un serveur qui démarre automatiquement lorsque le module d'entrée est exécuté. Cela vous permet de déployer plus facilement votre compilation sur un hôte sans avoir besoin de code supplémentaire.

```js title="astro.config.mjs" {6}
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  adapter: node({
    mode: 'middleware',
  }),
});
```

### `experimentalDisableStreaming`

<p>
**Type :** `boolean` <br />
**Par défaut :** `false`<br />
<Since v="9.3.0" pkg="@astrojs/node" />
</p>

Désactive le [streaming HTML](/fr/guides/on-demand-rendering/#streaming-html) par défaut d'Astro pour les pages rendues à la demande.

Le streaming HTML améliore les performances et offre généralement une meilleure expérience aux visiteurs. Dans la plupart des cas, il est déconseillé de désactiver le streaming.

Cependant, lorsque vous devez désactiver le streaming HTML (par exemple, votre hébergeur ne prend en charge que la mise en cache HTML non diffusée au niveau du CDN), vous pouvez désactiver le comportement par défaut :

```js title="astro.config.mjs" {7}
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  adapter: node({
    mode: 'standalone',
    experimentalDisableStreaming: true,
  }),
});
```

### `experimentalStaticHeaders`

<p>
  **Type :** `boolean` <br />
  **Par défaut :** `false`<br />
  <Since v="9.3.0"  pkg="@astrojs/node"/>
</p>

Si cette option est activée, l'adaptateur servira les en-têtes des pages pré-rendues à l'aide de l'objet `Response` lorsqu'il est fourni par les fonctionnalités Astro, telles que la politique de sécurité du contenu.

Par exemple, lorsque [la politique de sécurité du contenu expérimentale](/fr/reference/experimental-flags/csp/) est activée, `experimentalStaticHeaders` peut être utilisé pour ajouter les en-têtes CSP à l'objet `Response` au lieu de créer un élément `<meta>` :

```js title="astro.config.mjs" {10}
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  experimental: {
    csp: true
  },
  adapter: node({
    mode: 'standalone',
    experimentalStaticHeaders: true,
  })
});
```

### `experimentalErrorPageHost`

<p>
  **Type :** `string | URL` <br />
  **Par défaut :** `undefined`<br />
  <Since v="9.4.0" pkg="@astrojs/node"/>
</p>

Spécifie un hôte alternatif pour le chargement des [pages d'erreur personnalisées](/fr/basics/astro-pages/#page-derreur-404-personnalisée) pré-rendues.

Astro doit pouvoir charger votre page 404 afin de la renvoyer dans une réponse. Par défaut, Astro charge les pages d'erreur personnalisées pré-rendues depuis le même hôte que celui auquel la requête est adressée. Par exemple, si une requête est adressée à `https://example.com/page-inexistante`, Astro tentera de charger la page d'erreur pré-rendue depuis `https://example.com/404.html`.

Utilisez `experimentalErrorPageHost` lorsque votre page d'erreur personnalisée doit être chargée depuis un autre hôte, par exemple lorsque le serveur est exécuté derrière un proxy inverse ou dans un conteneur n'ayant pas accès à l'URL de l'hôte externe. Vous pouvez également l'utiliser lorsqu'il est plus efficace de charger la page d'erreur pré-rendue depuis localhost plutôt que via le réseau Internet public.

La valeur peut être une chaîne de caractères ou un objet URL. Il doit s'agir d'une URL complète, incluant le protocole (par exemple, `http://localhost:4321`). Astro chargera toujours la page d'erreur pré-rendue depuis le chemin racine, et les paramètres de chemin ou de requête seront ignorés.

```js
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  adapter: node({
    // Charger les pages depuis localhost, et non depuis l'URL publique.
    experimentalErrorPageHost: 'http://localhost:4321',
  })
});
```

## Utilisation

Tout d'abord, [effectuer une compilation](/fr/guides/deploy/#compiler-votre-site-localement). En fonction du `mode` sélectionné (voir ci-dessus), suivez les étapes appropriées ci-dessous :

### Middleware

Le point d'entrée du serveur est compilé dans `./dist/server/entry.mjs` par défaut. Ce module exporte une fonction `handler` qui peut être utilisée avec n'importe quel framework qui prend en charge les objets Node `request` et `response`.

Par exemple, avec Express :

```js title="run-server.mjs"
import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';

const app = express();
// Changez ceci en fonction de votre option `base` dans astro.config.mjs.
// Ils doivent correspondre. La valeur par défaut est "/".
const base = '/';
app.use(base, express.static('dist/client/'));
app.use(ssrHandler);

app.listen(8080);
```

Ou, avec Fastify (>4) :

```js title="run-server.mjs"
import Fastify from 'fastify';
import fastifyMiddie from '@fastify/middie';
import fastifyStatic from '@fastify/static';
import { fileURLToPath } from 'node:url';
import { handler as ssrHandler } from './dist/server/entry.mjs';

const app = Fastify({ logger: true });

await app
  .register(fastifyStatic, {
    root: fileURLToPath(new URL('./dist/client', import.meta.url)),
  })
  .register(fastifyMiddie);
app.use(ssrHandler);

app.listen({ port: 8080 });
```

De plus, vous pouvez également passer un objet qui sera accessible avec `Astro.locals` ou dans le middleware Astro :

```js title="run-server.mjs"
import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';

const app = express();
app.use(express.static('dist/client/'));
app.use((req, res, next) => {
  const locals = {
    title: 'Nouveau titre',
  };

  ssrHandler(req, res, next, locals);
});

app.listen(8080);
```

Notez que le mode middleware ne permet pas de servir des fichiers. Vous devrez configurer votre framework HTTP pour qu'il le fasse pour vous. Par défaut, les ressources du client sont écrites dans `./dist/client/`.

### Standalone

En mode standalone, un serveur démarre lorsque le point d'entrée du serveur est exécuté. Par défaut, il est compilé dans `./dist/server/entry.mjs`. Vous pouvez le lancer avec :

```sh
node ./dist/server/entry.mjs
```

En mode standalone, le serveur gère le service de fichiers en plus des routes de pages et d'API.

#### Hôte et port personnalisés

Vous pouvez modifier l'hôte et le port sur lesquels le serveur standalone s'exécute en les passant comme variables d'environnement au moment de l'exécution :

```sh
HOST=0.0.0.0 PORT=4321 node ./dist/server/entry.mjs
```

#### HTTPS

Par défaut, le serveur standalone utilise le protocole HTTP. Cela fonctionne bien si vous avez un serveur proxy en face de lui qui utilise HTTPS. Si vous avez besoin que le serveur standalone utilise HTTPS lui-même, vous devez fournir votre clé et votre certificat SSL.

Vous pouvez passer le chemin vers votre clé et votre certificat via les variables d'environnement `SERVER_CERT_PATH` et `SERVER_KEY_PATH`. Voici comment vous pouvez les transmettre avec Bash :

```bash
SERVER_KEY_PATH=./private/key.pem SERVER_CERT_PATH=./private/cert.pem node ./dist/server/entry.mjs
```

#### Ressources

En mode standalone, les ressources de votre dossier `dist/client/` sont servies par le serveur standalone. Vous pouvez déployer ces ressources sur un CDN, auquel cas le serveur ne les servira jamais. Mais dans certains cas, comme les sites intranet, il est possible de servir les ressources statiques directement depuis le serveur d'application.

Les ressources dans le dossier `dist/client/_astro/` sont celles générées par Astro. Celles-ci sont toutes nommées avec un hachage et peuvent donc recevoir de longs en-têtes de cache. En interne, l'adaptateur ajoute cet en-tête pour ces ressources :

```
Cache-Control: public, max-age=31536000, immutable
```

## Sessions

L'[API Sessions](/fr/guides/sessions/) d'Astro vous permet de stocker facilement les données utilisateur entre chaque requête. Ceci peut être utilisé pour des éléments tels que les données et préférences utilisateur, les paniers d'achat et les identifiants d'authentification. Contrairement au stockage des cookies, la taille des données est illimitée et elles peuvent être restaurées sur différents appareils.

Astro utilise le système de fichiers local pour le stockage des sessions avec l'adaptateur Node. Si vous préférez utiliser un autre pilote de stockage de session, vous pouvez le spécifier dans votre configuration Astro. Consultez [la référence de configuration `session`](/fr/reference/configuration-reference/#sessiondriver) pour plus de détails.

## Variables d'environnement

Lorsque vous utilisez des secrets avec [`astro:env`](/fr/guides/environment-variables/#variables-denvironnement-avec-sûreté-du-typage) ou `process.env` au moment de l'exécution, ni Astro ni l'adaptateur ne chargent les variables d'environnement pour vous.

Certains hôtes peuvent exposer les variables d’environnement que vous configurez via leur tableau de bord pendant la compilation et lors de l’exécution. Consultez la documentation de votre hôte pour définir et utiliser les variables d'environnement au sein de la plate-forme concernée.

Lors de l'auto-hébergement, vous pouvez charger des variables d'environnement via des commandes CLI ou des fichiers de configuration, selon le cas :

<Tabs>
  <TabItem label="Intégré à la commande">
  ```shell
  DB_HOST=... DB_PASSWORD=... node ./dist/server/entry.mjs
  ```
  </TabItem>
  <TabItem label="dotenvx">
  ```shell
  npx dotenvx run -- node ./dist/server/entry.mjs
  ```
  </TabItem>
  <TabItem label="Docker">
  ```docker title="Dockerfile"
  FROM node:lts AS runtime
  WORKDIR /app

  COPY . .

  RUN npm install
  RUN npm run build

  ENV DB_HOST=...
  ENV DB_PASSWORD=...
  CMD node ./dist/server/entry.mjs
  ```
  </TabItem>
</Tabs>
